/*******************************************************************************
 * Copyright (c) 2003, 2004 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Common Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/cpl-v10.html
 * 
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
module dwt.browser.browserlisteners;


private import dwt.dwt;

private import dwt.browser.browser;
private import dwt.browser.website;
private import dwt.browser.browserevents;
private import dwt.internal.dwteventlistener;

/**
 * This listener interface may be implemented in order to receive
 * a {@link WindowEvent} notification when a {@link Browser} is 
 * about to be closed and when its host window should be closed
 * by the application.
 * 
 * @see Browser#addCloseWindowListener(CloseWindowListener)
 * @see Browser#removeCloseWindowListener(CloseWindowListener)
 * @see OpenWindowListener
 * @see VisibilityWindowListener
 * 
 * @since 3.0
 */
public interface CloseWindowListener : DWTEventListener {

/**
 * This method is called when the window hosting a {@link Browser} should be closed.
 * Application would typically close the {@link org.eclipse.dwt.widgets.Shell} that
 * hosts the <code>Browser</code>. The <code>Browser</code> is disposed after this
 * notification.
 *
 * <p>The following fields in the <code>WindowEvent</code> apply:
 * <ul>
 * <li>(in) widget the <code>Browser</code> that is going to be disposed
 * </ul></p>
 *
 * @param event the <code>WindowEvent</code> that specifies the <code>Browser</code>
 * that is going to be disposed
 * 
 * @see org.eclipse.dwt.widgets.Shell#close()
 * 
 * @since 3.0
 */ 
public void close(WindowEvent event);
}

/**
 * This listener interface may be implemented in order to receive
 * a {@link LocationEvent} notification when a {@link Browser}
 * navigates to a different URL.
 * 
 * @see Browser#addLocationListener(LocationListener)
 * @see Browser#removeLocationListener(LocationListener)
 * 
 * @since 3.0
 */
public interface LocationListener : DWTEventListener {

/**
 * This method is called when the current location is about to be changed.
 * <p>
 *
 * <p>The following fields in the <code>LocationEvent</code> apply:
 * <ul>
 * <li>(in) location the location to be loaded
 * <li>(in) widget the <code>Browser</code> whose location is changing
 * <li>(in/out) doit can be set to <code>false</code> to prevent the location
 * from being loaded 
 * </ul>
 * 
 * @param event the <code>LocationEvent</code> that specifies the location
 * to be loaded by a <code>Browser</code>
 * 
 * @since 3.0
 */ 
public void changing(LocationEvent event);

/**
 * This method is called when the current location is changed.
 * <p>
 *
 * <p>The following fields in the <code>LocationEvent</code> apply:
 * <ul>
 * <li>(in) location the current location
 * <li>(in) top <code>true</code> if the location opens in the top frame or
 * <code>false</code> otherwise
 * <li>(in) widget the <code>Browser</code> whose location has changed
 * </ul>
 * 
 * @param event the <code>LocationEvent</code> that specifies  the new
 * location of a <code>Browser</code>
 * 
 * @since 3.0
 */ 
public void changed(LocationEvent event);

}


/** 
 * This listener interface may be implemented in order to receive
 * a {@link WindowEvent} notification when a  new {@link Browser}
 * needs to be provided by the application.
 * 
 * @see Browser#addOpenWindowListener(OpenWindowListener)
 * @see Browser#removeOpenWindowListener(OpenWindowListener)
 * @see CloseWindowListener
 * @see VisibilityWindowListener
 * 
 * @since 3.0
 */
public interface OpenWindowListener : DWTEventListener {

/**
 * This method is called when a new window needs to be created.
 * <p>
 *
 * <p>The following fields in the <code>WindowEvent</code> apply:
 * <ul>
 * <li>(out) browser the new <code>Browser</code> that will host the 
 * content of the new window. If it is left <code>null</code>, the navigation
 * is cancelled and no new window is opened.</p>
 * <li>(in) widget the <code>Browser</code> that is requesting to open a 
 * new window
 * </ul>
 * 
 * @param event the <code>WindowEvent</code> that needs to be passed a new
 * <code>Browser</code> to handle the new window request
 * 
 * @since 3.0
 */ 
public void open(WindowEvent event);
}



/**
 * This listener interface may be implemented in order to receive
 * a {@link ProgressEvent} notification when a {@link Browser}
 * makes a progress in loading the current URL or when the
 * current URL has been loaded.
 * 
 * @see Browser#addProgressListener(ProgressListener)
 * @see Browser#removeProgressListener(ProgressListener)
 * @see Browser#getUrl()
 * 
 * @since 3.0
 */
public interface ProgressListener : DWTEventListener {
	
/**
 * This method is called when a progress is made during the loading of the 
 * current location.
 * <p>
 *
 * <p>The following fields in the <code>ProgressEvent</code> apply:
 * <ul>
 * <li>(in) current the progress for the location currently being loaded
 * <li>(in) total the maximum progress for the location currently being loaded
 * <li>(in) widget the <code>Browser</code> whose current URL is being loaded
 * </ul>
 * 
 * @param event the <code>ProgressEvent</code> related to the loading of the
 * current location of a <code>Browser</code>
 * 
 * @since 3.0
 */   
public void changed(ProgressEvent event);
	
/**
 * This method is called when the current location has been completely loaded.
 * <p>
 *
 * <p>The following fields in the <code>ProgressEvent</code> apply:
 * <ul>
 * <li>(in) widget the <code>Browser</code> whose current URL has been loaded
 * </ul>
 * 
 * @param event the <code>ProgressEvent</code> related to the <code>Browser</code>
 * that has loaded its current URL.
 * 
 * @since 3.0
 */
public void completed(ProgressEvent event);
}



/**
 * This listener interface may be implemented in order to receive
 * a {@link StatusTextEvent} notification when the status text
 * for a {@link Browser} needs to be updated.
 * 
 * @see Browser#addStatusTextListener(StatusTextListener)
 * @see Browser#removeStatusTextListener(StatusTextListener)
 * 
 * @since 3.0
 */
public interface StatusTextListener : DWTEventListener {

/**
 * This method is called when the status text is changed. The
 * status text is typically showed in the status bar of a browser 
 * application. 
 * <p>
 *
 * <p>The following fields in the <code>StatusTextEvent</code> apply:
 * <ul>
 * <li>(in) text the modified status text
 * <li>(in) widget the <code>Browser</code> whose status text is changed
 * </ul>
 * 
 * @param event the <code>StatusTextEvent</code> that contains the updated
 * status description of a <code>Browser</code>
 * 
 * @since 3.0
 */
public void changed(StatusTextEvent event);
}


/**
 * This listener interface may be implemented in order to receive
 * a {@link TitleEvent} notification when the title of the document
 * displayed in a {@link Browser} is known or has been changed.
 * 
 * @see Browser#addTitleListener(TitleListener)
 * @see Browser#removeTitleListener(TitleListener)
 * 
 * @since 3.0
 */
public interface TitleListener : DWTEventListener {

/**
 * This method is called when the title of the current document
 * is available or has changed.
 * <p>
 *
 * <p>The following fields in the <code>TitleEvent</code> apply:
 * <ul>
 * <li>(in) title the title of the current document
 * <li>(in) widget the <code>Browser</code> whose current document's
 * title is known or modified
 * </ul>
 * 
 * @param event the <code>TitleEvent</code> that contains the title
 * of the document currently displayed in a <code>Browser</code>
 * 
 * @since 3.0
 */
public void changed(TitleEvent event);
}



/** 
 * This listener interface may be implemented in order to receive
 * a {@link WindowEvent} notification when a window hosting a
 * {@link Browser} needs to be displayed or hidden.
 * 
 * @see Browser#addVisibilityWindowListener(VisibilityWindowListener)
 * @see Browser#removeVisibilityWindowListener(VisibilityWindowListener)
 * @see OpenWindowListener
 * @see CloseWindowListener
 * 
 * @since 3.0
 */
public interface VisibilityWindowListener : DWTEventListener {
	
/**
 * This method is called when the window hosting a <code>Browser</code> 
 * is requested to be hidden. Application would typically hide the
 * {@link org.eclipse.dwt.widgets.Shell} that hosts the <code>Browser</code>.
 * <p>
 *
 * <p>The following fields in the <code>WindowEvent</code> apply:
 * <ul>
 * <li>(in) widget the <code>Browser</code> that needs to be hidden
 * </ul>
 *
 * @param event the <code>WindowEvent</code> that specifies the
 * <code>Browser</code> that needs to be hidden
 * 
 * @see org.eclipse.dwt.widgets.Shell#setVisible(boolean)
 * 
 * @since 3.0
 */ 
public void hide(WindowEvent event);

/**
 * This method is called when the window hosting a <code>Browser</code>
 * is requested to be displayed. Application would typically set the 
 * location and the size of the {@link org.eclipse.dwt.widgets.Shell} 
 * that hosts the <code>Browser</code>, if a particular location and size
 * are specified. The application would then open that <code>Shell</code>.
 * <p>
 *
 * <p>The following fields in the <code>WindowEvent</code> apply:
 * <ul>
 * <li>(in) widget the <code>Browser</code> to display
 * <li>(in) location the requested location for the <code>Shell</code> 
 * hosting the browser. It is <code>null</code> if no location is set. 
 * <li>(in) size the requested size for the <code>Browser</code>.
 * The client area of the <code>Shell</code> hosting the
 * <code>Browser</code> should be large enough to accomodate that size.
 * It is <code>null</code> if no size is set.
 * </ul>
 *
 * @param event the <code>WindowEvent</code> that specifies the
 * <code>Browser</code> that needs to be displayed
 * 
 * @see org.eclipse.dwt.widgets.Control#setLocation(org.eclipse.dwt.graphics.Point)
 * @see org.eclipse.dwt.widgets.Control#setSize(org.eclipse.dwt.graphics.Point)
 * @see org.eclipse.dwt.widgets.Shell#open()
 * 
 * @since 3.0
 */ 
public void show(WindowEvent event);

}


